/*
 * Copyright 2013 Sigurd Randoll <srandoll@digiway.de>.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package de.digiway.rapidbreeze.server.model.storage;

import java.io.IOException;
import java.io.InputStream;
import java.net.URL;

/**
 * A {@linkplain StorageProviderDownloadClient} represents a client of a
 * {@linkplain StorageProvider} at runtime level. It handles the communication
 * between the server application and the hoster. It manages the authentication
 * and the creation of a {@linkplain InputStream} to download from a specifieid
 * {@linkplain URL}. One instance of this client is responsible to handle all
 * future actions.
 *
 * @author Sigurd Randoll <srandoll@digiway.de>
 */
public interface StorageProviderDownloadClient {

    /**
     * Returns the name of the StorageProviderDownloadClient.
     *
     * @return name
     */
    public String getName();

    /**
     * Tries to authenticate at the storage provider with the provided
     * credentials. The result of the authentication should be kept inside the
     * class and should be returned by
     * {@linkplain StorageDownload#getAuthenticationStatus()}.
     *
     * @param username
     * @param password
     */
    public void authenticate(String username, String password);

    /**
     * Retrieves the current {@linkplain AuthenticationStatus} at the
     * {@linkplain StorageProvider} for the current StorageDownload.
     *
     * @return an enum object representing the current state.
     */
    public AuthenticationStatus getAuthenticationStatus();

    /**
     * Starts the download of the specified URL starting at the given offset.
     *
     * @param url
     * @param offset
     * @return
     * @throws IOException will be thrown on any IO related exception.
     */
    public InputStream start(URL url, long offset) throws IOException;

    /**
     * Returns the current Status of the given url, e.g. file size, filename,
     * whether it is available or not and so on.
     *
     * @return an instance of the type {@linkplain UrlStatus} which can be used
     * to get information about the URL.
     */
    public UrlStatus getUrlStatus(URL url);

    /**
     * Checks if the storage download instance is able to handle the given URL.
     *
     * @param url
     * @return true if it can handle it
     */
    public boolean canHandle(URL url);
}
